• The projects list - Below the divider line in this menu is a list of the currently defined projects. The "current" project is the checkmarked one. Selecting a project from this menu makes it the current project, and switches the current checkout dir to the one you defined for that project.
• Refresh - This command will refresh the list of projects shown in this menu by asking SourceSare for the list of currently defined projects. This can take an awfully long time when there are many projects defined. Therefore, Source Manager allows you to only get this list when you think it might have changed (i.e. when you think the projects list might be stale due to someone having created new projects or deleted some).
• Remove... - This will just put up a little alert telling you how to Remove a project. Removing a project makes it invisible, sort of a virtual delete. However, removed projects can be recovered by using SourceSafe's Recover command (which you'll have to type into the ToolServer worksheet), so they're not really deleted. If you want to permanently remove a project, in order to save disk space, use the SS PURGE command (you'll have to type this in by hand, in the ToolServer Worksheet).
Checkout Dirs SubMenu
• The checkout dirs list - Below the divider line in this menu is a list of all the currently known checkout directories. Source Manager gets to "know" about a checkout dir in two ways: 1. by directories you specify in the "Edit CheckOut Dirs" window, and 2. directories Source Manager encounters when you drag folders to it. It combines these two sources to make this list. When you select a project from the Projects menu, Source Manager will automatically make the proper checkout directory current (if you defined one for that project).
• Set or Other - when there are no known checkout dirs, this is called Set, otherwise it's called Other. In either case, this command lets you pick a directory to use as a checkout directory.
• Remember - This is quick way of permanently associating the current checkout dir with the current project. (the other way to do this is by using the Edit CheckOut Dirs command). It puts up a little dialog where you can confirm this operation.
Edit Checkout Dirs
• What it's for - This command brings up the "Edit CheckOut Dirs" window, where you can specify permanent associations of projects and directories. Source Manager saves the information you enter here in its preferences file.
• "All / Current Projects" - These radio buttons select between all known projects, or just the currently mounted ones. This is an option simply so that you don't have to look at all projects if all you're interested in are the currently mounted ones. If ToolServer isn't running, these buttons are disabled, and are set to "All".
• "Recursive" column - This column is for specifying whether a Get All From command should be recursive or not, for the given project. You would want recursion if your local folder hierarchy mirrors the project hierarchy. That way, you only need to specify checkout dirs for top-level projects. If you don't want recursion, specify a directory for each project and subproject you intened to work with.
Edit Project Groups
• What it's for - This command brings up the "Edit Project Groups" dialog, where you can define and edit project groups. Project groups show up in the Get All From command's submenu. Thus, you can execute one Get All From command to have SM get all files from all the projects defined in that group. The files will go into the dirs you specified for each project using the Edit CheckOut Dirs command (above). This is especially handy when your local folders don't match the project hierarchy, or when the files you need are from multiple top-level projects.
• Available Projects - This lists all the projects Source Manager knows about. You can add one of these projects to the current group by double-clicking it, or by clicking the Add Project button.
• Projects In Group - This lists the projects in the current group. You can choose remove projects from this list by double-clicking them or clicking the Remove Project button.
• To create a new group - Click on the Current Project popup, and select Create New Group.
Options Menu - Warn Unexpected CheckOut Dirs
• Warn Unexpected CheckOut Dirs - Use this option if you have defined checkout dirs for each project you work with (highly recommended). Armed with that information, SM can determine if the proper CheckOut dir is selected when you do a command, and will warn you if it's not. You'll almost never see this warning, since SM does its utmost to insure the proper dir is selected, but you can defeat it if you want.
Commands which don't require a selection to be made in the table
• Launch ToolServer - If ToolServer isn't already running, you can launch it using this command. The first time you use this command, Source Manager will ask you to find ToolServer and offer to find it for you. From then on, even after quitting and re-running, Source Manager will remember where it is so you won't be asked to find it again (unless you move it). Tip: Hold down the shift key when you choose this command in order to invoke the Find dialog where you can manually find a different ToolServer, in case you have more than one on your disk.
• Create New Project - Use this command to create a new project in the SourceSafe database. It asks you to name the new project using a full SourceSafe pathname. SourceSafe pathnames have slashes ("/") as project delineators. You'll notice that the default pathname in the dialog is the current project. This can save you some typing: prior to choosing this command, select the project under which you want to create the new project, then choose this command and tack on a slash followed by the new project's name. When you click OK, a new project will be created. SM will then remind you to update your UserStartupTS file if you wish to associate a permanent CheckOut dir with this new project.
• Get All From - Check out (read-only) all newer files from the current project or project group. The first item in this submenu will be the current project. If there are any other items in this menu, they are project groups (below a divider). You can define project groups using the Edit Project Groups command. The files will go into the dirs you defined for each project in Edit CheckOutDirs.
Tip: to get non-recursively (i.e. current project only, no subprojects), hold down the option key when choosing this command.
• Show Differences - This command provides a convenient way of determining whether your files are stale, or whether your have some new files that need to be added to the database. It recursively compares the current project to your current CheckOut dir (this process can take awhile). It will then create tables which show you the differences and allow you to synchronize to the database by doing the appropriate command. For example, if it finds that there are some files in the project that do not exist in your CheckOut dir, it will create a Project Browser table containing those files, and it will call it "SourceSafe files not in your local dir". You could then select those files and click "Get" to get those files. If it finds files in your CheckOut dir that do not exist in the project, it will create a normal table called "Local files not in SourceSafe". You could then select those files and choose "Add" to add them to the SourceSafe database. This command will also find files that are different in some way from the project database and create tables for them too, called "SourceSafe files different from local files". Generally, these would be files that have been modified and therefore need to be checked in. If SM creates no tables as a result of this command, then you are totally in sync with the database.
• Rename Modified And Check Out - This command lets you merge mod-read-only files into the database. What it does is it renames your modified file to have a "$$$" suffix, then checks out the latest revision from the database, and shows the two files in the table. At that point, you can select the two files, and, if you own BBEdit, choose "Compare Two Files", and BBEdit will come to front, all set up, showing you the differences between the two files. You can then merge your "$$$" file into the checked out file, and return to SM. When you return, you can then check in the checked out file, and trash the "$$$" file (SM will automatically offer to trash it for you).
This command operates in two ways depending on whether or not you have a table up and something is selected. If so, it only operates on the selected files which are mod-read-only. If you have nothing selected, or no table is up, it goes through the currently selected CheckOut directory and operates on any and all mod-read-only files it finds in that directory (non-recursively). You could then drag that folder onto SM and see all the files paired right next to each other (since their names only differ by their suffix) ready to do your compares.
• Open Project Browser - Open a Project Browser window for the current project. In this window, you will see a table of the files in that project. When this table first opens, it only shows filenames, not other information, in order to come up nice and quickly. To see more information on a particular file, select the file and click the Info button, or simply double-click in the Filename column. A new window will open, showing all revisions of that file. To see the comment of a particular revision in its entirety (instead of just what you can see in the table) double-click the comment cell. A window will open showing that comment. To change the comment, simply type in something new in this window and choose File>Save.
Commands which operate on the selected files in a table
• Add - Add one or more new files to the current project. The files must be orphans (i.e. no 'ckid' resource). The opposite of Add is Remove.
• Remove - Removes the file from the project database. After that, it “orphans” the files on your disk (i.e. removes the ‘ckid’ resource), which is generally what you would want to do after Remove. Removing a file does not actually free up space in the database, because SourceSafe allows you to Recover a file that has been Removed. To permanently delete the file, use SourceSafe's Purge command (Source Manager doesn't provide a Purge command in its menus, but you can type it into the ToolServer Worksheet).
• CheckIn - SourceSafe actually calls this "Update", but I like Projector's term "Check In" better. This command checks in the selected files to the current project. Unlike Projector, SourceSafe does not allow you to attempt to check in a mod-read-only file (only checked out files). But Source Manager overcomes that limitation for the user by doing the necessary checkout behind your back, manipulating ckid's, and then checking it in. Here's what SM does when you check in a mod-read-only file:
1. SM first checks the database to see if there's a later revision in the database. If there is, it will alert you and offer to set up a merge using BBEdit. If not, it goes on to step 2.
2. SM renames your mod-read-only file to have a "$$$" suffix because it is about to check out the latest revision into the same folder.
3. SM checks out the latest revision of the file. If it can't be checked out because someone else has it checked out, it will alert you and then will rename your $$$ file back to its original name. You can then get up from your cube and go complain to that person and have them check in, and chastise them for hogging the database (a little joke, ha ha...or is it?).
4. SM grabs a copy of your file's comment (from the 'ckid'), then replaces your file's 'ckid' with that of the checked out file, and sticks the comment back into that 'ckid'.
5. SM checks in the checked out file and offers to move your $$$ file to the trash.
• CheckOut - Check out the selected files for modification. Remember that SourceSafe doesn't really know the location of the files you have selected, it simply gets told their names, and it will look in the current CheckOut dir for the actual files. Source Manager will, however, warn you (if you enable the warning option) when it finds that the current CheckOut dir does not match the current project (as defined by your UserStartupTS). But even without the warning, the worst that will happen is the files will get checked out to the wrong directory.
• Get - Get read-only copies of the latest revision of the selected files. The files will go into the current CheckOut dir, replacing older read-only files. You needn't worry about losing any changes you've made to your files, since this command only overwrites those files which are currently read-only. It skips over any others. If you want to get all latest revisions for the entire project, use the Get All command instead.
• UnCheckOut - Cancel the checkout of the selected files. You’ll lose any changes you may have made since checkout and the file will become Read-Only again.
• Get SourceSafe Cmt Into Ckid - Get the database's comment for the latest revision of the selected file into the your file's 'ckid'. The reason this command exists is that when you check in a file, SourceSafe attaches a new 'ckid' to your file that has its comment field blank. But what if you want to see the comment this file was checked in with. That's the purpose of this command. It simply retrieves that comment and puts it back into your 'ckid'. An alternative to this is to open a project browser, where you can look at the files in the database and see their comments.
• Compare To Previous Revision - This is for comparing your local file to any previous revision of the same file in the project database (you must have BBEdit in order to use this command). This command is only enabled when you have exactly one file selected in your active table. This menu item is a submenu containing a list of the revision numbers available. For example if your local file is revision 4, you'll see 4 items in the menu: "1","2","3" and "4". Choose which revision you'd like to compare your local file to, and SM will then check that revision out (read-only) from the database into a temporary folder SM creates on your disk (located insided SM's folder). It then sends the "Compare Two Files" command to BBEdit and switches BBEdit to the front, where you'll see the comparison all set up for you. When you quit SM, it will delete the temporary folder it creates (and the files in it).
